Background

When you have a search open in the app (say, a grid of card tiles in operator mode), that search is live: the realm notifies the browser when its contents change, and the search updates itself without a page reload.

Search results are mostly served as prerendered HTML — the server renders each card ahead of time and the search just displays that HTML, which is much cheaper than instantiating every card in the browser. Recently, producing that HTML was split out of indexing into its own background job: when a card changes, its searchable data is updated first (fast), and the HTML re-render follows afterwards on its own channel (slow — rendering is orders of magnitude more expensive). When the HTML lands, the realm sends the browser a prerender_html event listing which cards got fresh HTML.

Until now, an open live search reacted to that event by re-running the entire search: re-send the query, re-fetch every result, rebuild every row. That's always correct, but consider what actually changed: the set of cards matching the query didn't move at all — only the pictures of some of them are newer. If your search shows 200 cards and one of them was re-rendered, we re-fetched all 200.

What this PR does

On a prerender_html event, the live search now updates only the cards the event names, and only if their HTML is actually newer than what's on screen — instead of re-running the whole search.

To know "newer," every search result already carries two version numbers (called generations): one for its searchable data and one for its HTML. The event carries a generation too. So the resource can look at each row on screen and decide: is this card in the event's list, and is the event's generation higher than the HTML I'm holding? Only such rows need attention — often none do, and then the event costs nothing.

For each row that does need attention, the browser asks the server for just that one card's rendering, using standard HTTP caching: the request says "I have version 12:10 — anything newer?" (an If-None-Match header). The server answers either:

• "No, that's still current" (304) — the row on screen is left completely untouched. This matters beyond saving bytes: if the user had interacted with that card and it had been upgraded to a fully live card instance, replacing the row would have knocked it back to static HTML.
• "Yes, here's the new one" (200) — the fresh rendering is swapped into that row's slot. Every other row keeps its exact object identity, so nothing else re-renders. (If the new content turns out identical to what's on screen, the row object is kept too.)

Events can arrive while a refresh is already underway — another batch of HTML landing, or an ordinary index event, possibly for a different workspace the search spans. The queued work survives all of these: it is only discarded once it has actually been applied, and an index event arriving mid-refresh absorbs the pending HTML updates into its own (full) re-fetch rather than dropping them. Each invalidated card is tracked with its own generation, since generations are per-workspace counters and can't be compared across workspaces.

What still re-runs in full

• Free-text searches (queries with a matches filter, i.e. "search cards containing the word pigeon"). These match against a text extraction that is produced by the render, so a prerender_html event genuinely can add or remove results — membership isn't stable. They keep the old behavior: re-run the whole search.
• Searches that ask for card data only (no HTML). These run in a mode that hides cards whose rendering failed — and a render failure is announced by, precisely, a prerender_html event. So for these queries the event can change which cards appear at all, and only a full re-run picks that up.
• Anything the one-card request can't express: paginated searches (we can't splice one row into a page-limited window and keep the totals honest), and queries selecting multiple renderings per card or individual card fields.
• Any error along the way: if the one-card request fails or returns something unexpected, the resource falls back to the full re-run rather than leaving a stale row. The fallback is the previous behavior, so the worst case of this PR is exactly what happened before it on every event.

The older live-search resource that returns card instances deliberately keeps re-running on every prerender_html event, for the same reason as the card-data-only case above: it hides cards with render failures, so these events can change its results even though instances carry no HTML.

Where the changes live

• packages/host/app/resources/search-entries.ts — the live-search resource: decides which path an event takes, performs the per-card refreshes, splices results in place.
• packages/host/app/services/store.ts — new fetchCardEntry: the "give me this one card's rendering, unless mine is current" HTTP request. (The server endpoint it talks to already exists.)
• packages/runtime-common — small helpers: detect a free-text filter anywhere in a query, read the requested format off a query, validate the one-card response shape.

Testing

Integration tests cover: an event refreshes only the named card and issues no full re-query; a 304 leaves the row object untouched; a card already up to date or not on screen causes no request at all; a card that matched before its HTML ever rendered gets upgraded; free-text and card-data-only queries still re-run in full; a failed one-card request falls back to the full re-run; events arriving mid-refresh — both another HTML batch and an index event on a different workspace — neither drop nor duplicate work; and a real (unstubbed) round trip against the server proving the version tag the browser reconstructs matches the server's, so the 304 path genuinely fires. Unit tests pin the helper that reads the requested format off a query, including malformed input.

🤖 Generated with Claude Code